/*  This file is Copyright 2010 Hampton Smith
 * 
 *  This file is part of Adventure! a text-adventure game engine by Hampton
 *  Smith.
 *
 *  Adventure! is free software: you can redistribute it and/or modify
 *  it under the terms of the GNU General Public License as published by
 *  the Free Software Foundation, either version 3 of the License, or
 *  (at your option) any later version.
 *
 *  Adventure! is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 *  GNU General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License
 *  along with Adventure!.  If not, see http://www.gnu.org/licenses/.
 */

package edu.clemson.cs.hamptos.adventure;

/**
 * <p>An <code>AdventureParser</code> provides a bridge between the player's
 * descriptions of objects and the associated <code>AdventureTarget</code>s that
 * represent them.  It reads in textual commands and transforms them into
 * <code>AdventureCommand</code>s.</p>
 */
public interface AdventureParser {

    /**
     * <p>Parses the given <code>command</code> into an
     * <code>AdventureCommand</code>.  It does this by matching textual
     * descriptions with the descriptions of items in the player's inventory
     * and those in the player's current location.</p>
     * 
     * @param command The original, textual command.  Non-null.
     * @param e The <code>AdventureEngine</code> that represents the current
     *    game.  The parser can use this to find a list of targets
     *    in the player's inventory or in the player's current location.
     *
     * @return An <code>AdventureCommand</code> representing the given textual
     *    command.
     *
     * @throws NoSuchTargetException If the parser cannot match a named object
     *    to an <code>AdventureTarget</code>.
     */
    public AdventureCommand parse(String command, AdventureEngine e)
            throws NoSuchTargetException;
}
